\documentclass[a4paper,10pt]{article}
\usepackage{listings}
\usepackage{color}
\usepackage{url}

\lstset{language=Java}
\lstset{breaklines=true, numbers=left}
\lstset{tabsize=4}

\definecolor{CommentColor}{rgb}{0,0.5,0} 
\definecolor{KeywordColor}{rgb}{0,0,0.5}

\lstset{commentstyle=\scriptsize\color{CommentColor}\itshape}
\lstset{keywordstyle=\scriptsize\color{KeywordColor}\bfseries}
\lstset{basicstyle=\scriptsize}
\lstset{identifierstyle=\scriptsize}
\lstset{stringstyle=\scriptsize}

% \lstset{basicstyle=\ttfamily}

\newcommand{\src}[1]{\lstinline[basicstyle=\normalsize\ttfamily,keywordstyle=\normalsize\ttfamily,identifierstyle=\normalsize\ttfamily]|#1|}

\newcommand{\short}{\item[Short]}
\newcommand{\why}{\item[Reason]}
\newcommand{\clients}{\item[Clients]}

\title{DockingFrames 1.1.0 - Transition}
\author{Benjamin Sigg}

\begin{document}

\maketitle
\tableofcontents
\newpage


\begin{abstract}
This document describes the most important changes between versions, and how developers should change their application in order to use new features. This document does not make any distinction between the core-library and the common-project. Not all changes are listed up in this document, only those enhancements which might be interesting for the majority of developers.
\end{abstract}

\section{Version 1.0.3}
Version 1.0.3 emphasizes on background enhancements. The API remains unchanged for most parts.
\subsection{Incompatibilities}
These changes break with the API from 1.0.2, clients must change their interfaces in order to work properly.

\subsubsection{DefaultKeyboardController}
\begin{description}
\short The class \src{DefaultkeyBoardController} has been renamed to \\\src{DefaultKeyboardController} 
\why The new name looks better
\clients Replace any occurrence of \src{DefaultkeyBoardController} to \\\src{DefaultKeyboardController}
\end{description}

\subsubsection{DefaultDockable/DefaultCDockable}
\begin{description}
 \short \src{DefaultDockable} and \src{DefaultCDockable} now have \src{BorderLayout} set as default \src{LayoutManager}
 \why \src{BorderLayout} is the most often used \src{LayoutManager}.
 \clients If another \src{LayoutManager} than \src{BorderLayout} is needed, set it up.
\end{description}

\subsubsection{CDockableListener}
\begin{description}
 \short \src{CDockableListener} divided into \\\src{CDockableStateListener} and \src{CDockablePropertyListener}
 \why \src{CDockableListener} was to big. Most clients either need information about the state, or about the properties of a \src{CDockable}. The case that both informations are needed is seldom.
 \clients Need to decide which listener they implement. Note that \\\src{CDockableAdapter} implements both listeners, but not all methods get invoked when the adapter is registered only as one kind of listener.
\end{description}

\subsubsection{FlapDockStation}
\begin{description}
 \short \src{FlapDockStation}s layout is stored in a new format. The xml format will do the transition automatically, but the \src{DataInput/OutputStream} will not work properly.
 \why the old format did not carry enough information
 \clients Store the layout in xml-format and load it again to do the transition.
\end{description}

\subsubsection{XML}
\begin{description}
 \short \src{XElement} now extends \\\src{XContainer}, and no longer \src{XAttribute}. \src{XAttribute} extends \src{XContainer} as well.
 \why An element of a xml file is not an attribute, that is now reflected in the class structure
 \clients May need to replace some occurrences of \src{XAttribute} by \src{XContainer}
\end{description}

\subsubsection{DockTheme}
\begin{description}
 \short The common-project uses its own set of \src{DockTheme}s. Each theme \src{XTheme} gets replaced by \src{CXTheme}
 \why The new themes make use of the new \src{ColorMap}
 \clients Should use the new themes when possible. The old themes will work, but the user will see less features.
\end{description}

\subsubsection{DockFactory}
\begin{description}
 \short \src{DockFactories} can now create any \src{Object} they want, and are no longer required to create \src{DockLayout}s. \src{DockLayout} has been converted into a class that wraps the \src{Object} that was created by a DockFactory
 \why All \src{DockLayout}s need to do the same things, hence clients would need to write the same code over and over again. Clients have now more freedom in how to implement \src{DockFactory}
 \clients Should remove all occurrences of \src{implements DockLayout} and the methods \src{set/getFactoryId} that were defined in \src{DockLayout}
\end{description}


\subsection{Features}
This is the set of new features.

\subsubsection{SplitDockStation}
\begin{description}
 \short The tree of elements of a \src{SplitDockStation} is now accessible from outside and can be modified directly
 \why It is more intuitive to work directly with the tree, some new algorithms work on the tree and are easier to implement that way.
\end{description}

\subsubsection{SplitLayoutManager}
\begin{description}
 \short New \src{SplitLayoutManager} calculates where to drop, and how to divide, elements of a \src{SplitDockStation}
 \why New features, like the locked size of \src{CDockable}, were only possible if the behavior of a \src{SplitDockStation} can be changed on runtime.
\end{description}

\subsubsection{CDockable resize lock}
\begin{description}
 \short The size of a \src{CDockable} can be locked during resize of its parent. See \src{setResizeLocked}, a method of \src{AbstractCDockable}.
 \why This was a request from a user
\end{description}

\subsubsection{FlapLayoutManager}
\begin{description}
 \short \src{FlapDockStation} now uses \src{FlapLayoutManager} to arrange its children
 \why Exchangeable behavior was a requirement for new features in the common-project.
\end{description}

\subsubsection{ColorManager/ColorScheme}
\begin{description}
 \short Many graphical elements now use \src{ColorManager} and \src{ColorSchemes}
 \why Colors can now be exchanged by clients. The control goes deep, even the color of a single element can be exchanged without affecting other elements of the same kind.
\end{description}

\subsubsection{ColorMap}
\begin{description}
 \short \src{CDockable} uses a \src{ColorMap} to define special colors for tabs and titles that are related to the \src{CDockable}
 \why This was a request from a user
\end{description}

\subsubsection{LookAndFeel}
\begin{description}
 \short Changes of \src{LookAndFeel} noted by \src{DockController} and forwarded to all \src{UIListeners}.
 \why Because the \src{ColorManager} would not be informed of the new \\\src{LookAndFeel} otherwise
\end{description}

\subsubsection{CDockable resize request}
\begin{description}
 \short \src{CDockable}s can now request a size they would like to have, and in most environments they will get this size. See the method \src{setResizeRequest} of \src{AbstractCDockable}.
 \why This was a request from a user
\end{description}

\section{Version 1.0.4}
Version 1.0.4 introduces a few new features that add customizability
\subsection{Incompatibilities}
These changes break with the API from 1.0.3, clients must change their interfaces in order to work properly.

\subsubsection{Binary file format}
\begin{description}
\short The binary file format has been changed
\why The format now includes version numbers so that backwards compatibility should be possible in the next versions
\clients Need to delete all binary files. They might try to write their properties with the old version in xml, and then load the xml file with the new version. This should convert the files.
\end{description}

\subsubsection{DockableListener}
\begin{description}
\short Has an additional method \src{titleExchanged}
\why Allows to exchange a \src{DockTitle} while the \src{Dockable} is visible
\clients Need to update any class that implements \src{DockableListener}.
\end{description}

\subsubsection{Title visibility on CDockables}
\begin{description}
\short Any \src{CDockable} can now hide its titles at any time
\why user request
\clients Need to update any class implementing \src{CDockablePropertyListener} since that listener has an additional method \src{titleShownChanged}.
\end{description}

\subsubsection{BasicDropDownButtonHandler}
\begin{description}
\short Requests now a \src{BasicDropDownButtonTrigger} instead of a \\\src{BasicTrigger}
\why to allow steering any drop down action with the keyboard.
\clients unlikly to have an effect on any client
\end{description}

\subsubsection{CDockable.getClose}
\begin{description}
\short Method has been moved into \src{CommonDockable}
\why The action can now be replaced through \src{CDockable.getAction}.\\There is no need for any client to replace the action by replacing the whole \src{DockActionSource}
\clients should use \src{putAction}, a method of \src{AbstractCDockable} to exchange the close-action. No fix for clients which added additional elements to the close-source.
\end{description}

\subsubsection{CLocation}
\begin{description}
\short Additional \src{CLocations}, some methods have been moved
\why To allow the new \src{CStation} more flexible \src{CLocation}s were needed.
\clients No general solution available, clients should recompile their project and check all compiler errors.
\end{description}

\subsubsection{working area}
\begin{description}
\short Every \src{CStation} can now be a working area
\why To allow more flexibility in grouping \src{CDockable}s
\clients That should not be visible for any client using version 1.0.3
\end{description}


\subsection{Features}
This is the set of new features.

\subsubsection{Border around BubbleDisplayer}
\begin{description}
 \short BubbleDisplayer now shows a border if the title is not null, or if the dockable is not a station
 \why Looks better
\end{description}

\subsubsection{Backup factories (core)}
\begin{description}
 \short \src{DockFrontend} and \src{PredefinedDockSituation} can now use backup factories. These factories are used to load elements which should be in the cache, but are missing. In case of \src{DockFrontend} they are automatically added to the frontend.
 \why Removes the need to add all \src{Dockable}s to a \src{DockFrontend} before loading a layout from a file.
\end{description}

\subsubsection{Backup factories (common)}
\begin{description}
 \short \src{CControl} now supports lazy initialisation of \src{SingleCDockable}s through the \src{SingleCDockableBackupFactory}.
 \why saves memory
\end{description}

\subsubsection{Unregister factories from DockFrontend}
\begin{description}
 \short \src{DockFactory}s can now be unregistered from \src{DockFrontend}
 \why Was missing
\end{description}

\subsubsection{Action support keyboard}
\begin{description}
 \short \src{DockAction}s are triggered by pressing SPACE on the focused button, \src{DropDownAction}s pop up when the DOWN (non numpad) key is pressed
 \why Ongoing work to allow navigating in DF without the mouse.
\end{description}

\subsubsection{FocusTraversalPolicies}
\begin{description}
 \short New \src{FocusTraversalPolicy}s allow to navigate within all elements of a \src{DockableDisplayer} (including title).
 \why Ongoing work to allow navigating in DF without the mouse.
\end{description}

\subsubsection{override predefined actions}
\begin{description}
 \short \src{CDockable} has an additional method \src{getAction} which is used by various modules to override their default actions.
 \why Answer to a user request
\end{description}

\subsubsection{CBlank}
\begin{description}
 \short New action \src{CBlank}, which does not show anything.
 \why As value for \src{CDockable.getAction} when a predefined action should be hidden
\end{description}

\subsubsection{CStation}
\begin{description}
 \short Additional interface \src{CStation} in common. Two new stations: \\\src{CMinimizeArea} and \src{CGridArea}.
 \why Allows clients to add their own \src{DockStation}s to \src{CControl}, allows to create other layouts than the
 "one center, four minimize areas"-layout.
\end{description}

\subsection{Bugfixes}
These are the bugs that were fixed/

\subsubsection{BubbleDisplayer.getDockableInsets}
\begin{description}
 \short The method did not calculate its result correctly.
 \why A flaw in the design of \src{BasicDockableDisplayer}
\end{description}

\subsubsection{IndexOutOfBoundsException from ButtonPanel}
\begin{description}
 \short The exception was thrown when an invisible action was on the panel
 \why invisible actions were not considered when writing \src{ButtonPanel}
\end{description}

\subsubsection{Mode change of CDockable}
\begin{description}
 \short \src{CDockable} did not go into normalized-mode when externalized and never normalized before
 \why Properties were missing and could not be created automatically
\end{description}

\subsubsection{Opening maximized CDockable}
\begin{description}
 \short \src{CDockable} could not be opened maximized.
 \why framework got confused because \src{CDockable} did not have a parent.
\end{description}

\subsubsection{Unbind of DockAction called to often}
\begin{description}
 \short A \src{DockAction} could throw an exception "unbind called to often"
 \why When a \src{DockAction} was a child of a \src{MenuMenuHandler}, its \src{unbind} method was called even if the action was not displayed. However the \src{bind} action was called only if the action was displayed, so the internal counter was no longer correct. Every time a menu with such an action was shown, the counter was decremented by one. When it reached a value below 0, an exception was thrown. Since an action could be bound by many elements, the exception occured at random places.
\end{description}

\section{Version 1.0.5}
Version 1.0.5 brings the possibility to navigate around only by hitting some keys on the keyboard. When clicking the \src{ctrl+shift+e} combination, a dialog opens on which a \src{Dockable} can be selected.

\src{DockAction}s in button form can be activated with \src{space}, and the dropdown actions menu can be opened with the \src{arrow down} key.

This release contains some tricky incompatibilities which need to be handled very carefully.

\subsection{Incompatibilities}
The changes that need special care.

\subsubsection{DockStationListener}
\begin{description}
 \short The method \src{dockableSelected} of \src{DockStationListener} has an additional parameter that indicates which element was selected before the change.
 \why No need for listeners to store the old values.
 \clients Must carefully update all classes and interfaces that implement \\\src{DockStationListener}. Be especially careful not to mix up the new arguments with the old ones.
\end{description}

\subsubsection{DockableFocusListener}
\begin{description}
 \short The \src{DockableFocusListener} has been divided into two interfaces: \\\src{DockableFocusListener} and \src{DockableSelectionListener}. The\\remaining method in \src{DockableFocusListener} now takes a \\\src{DockableFocusEvent} and no longer directly the involved elements. The class \src{DockableFocusAdapter} has been deleted.
 \why Events allow further changes of the system without change of the \src{DockableFocusListener} itself. Since every client needs to update its methods anyway, \src{DockableFocusAdapter} could be deleted.
 \clients Should use \src{DockableFocusListener} instead of \\\src{DockableFocusAdapter}.
\end{description}

\subsubsection{DockTheme.getDockableSelection}
\begin{description}
 \short \src{DockTheme} has an additional method \src{getDockableSelection}.
 \why A \src{DockableSelection} is needed to change the focused \src{Dockable} using only the keyboard. Since \src{DockableSelection} is a graphical element, it has to be handled by the \src{DockTheme}.
 \clients Should implement the missing method in their \src{DockTheme}s. Using \src{DefaultDockableSelection} is an easy solution.
\end{description}

\subsubsection{tap-strip no longer painted by TapPainter}
\begin{description}
 \short \src{TabPainter} does no longer paint the tab-strip directly. It now creates a \src{TabStripPainter} that paints the strip.
 \why The new object can work with the color map.
 \clients Have to provide a \src{TabStripPainter} as well.
\end{description}

\subsubsection{KeyboardController does fire less events}
\begin{description}
 \short The \src{KeyboardController} does no longer fire events when it could not find the source-\src{Dockable} of the event. As a result the \src{KeyboardListener} does no longer receive \src{null} as argument of any of its methods.
 \why Events were fired which had nothing to do with the framework at all.
 \clients If they need all key events, then they can add a global \src{KeyListener} to \src{KeyboardController} using the method \src{addGlobalListener}.
\end{description}

\subsubsection{ComponentHierarchyObserver}
\begin{description}
 \short The \src{ComponentHierarchyObserver} includes more \src{Components} in its search. The \src{ComponentHierarchyObserverListener} now works with an event and does no longer receive all the elements as arguments.
 \why Allows more features to work correctly in restricted environments.
 \clients Need to be aware that not every \src{Component} that is found by the observer is a child of a \src{Dockable}.
\end{description}


\subsection{API and Layout}
A list of new API elements and changes that affect the layout.

\subsubsection{KeyStroke for closing Dockable}
\begin{description}
 \short The \src{KeyStroke} for closing a \src{CDockable} or \src{Dockable} has been changed from \src{ctrl+c} to \src{ctrl+F4}.
 \why Andrew pointed out, that \src{ctrl+c} is already used by many applications...
\end{description}

\subsubsection{New listeners}
\begin{description}
 \short There are new listeners, \src{CFocusListener}, \src{CKeyboardListener} and \\\src{CDoubleClickListener}, which can be added to \src{CDockable} or to \\\src{CControl} if all \src{CDockable}s should be monitored.
 \why Might be helpful for some applications
\end{description}

\subsubsection{ComponentHierarchObserver}
\begin{description}
 \short Clients can now add and remove \src{Component}s from the \\\src{ComponentHierarchyObserver}. The observer also includes \src{DockTitle}s in its search for \src{Component}s.
 \why Might become necessary for complex applications that run in a restricted environment.
\end{description}

\subsubsection{Root window for DockController}
\begin{description}
 \short The \src{DockController} can now find the root window of the application. The window can also be set directly using \src{setRootWindow}. If so, then the root window is added to the \src{ComponentHierarchyObserver}.
 \why Necessary to show small dialogs like the new \src{DockableSelector}
\end{description}

\subsubsection{FocusTraversalPolicies}
\begin{description}
 \short All \src{DockTheme}s now support \src{FocusTraversalPolicies}. Now each \\\src{DockAction} and all \src{Component}s of a \src{Dockable} can be reached by using only the keyboard.
 \why A nice feature for people which do not like the mouse
\end{description}

\subsubsection{Dialog to select focused Dockable}
\begin{description}
 \short The \src{DockableSelector} and \src{DockableSelection} allow users to select the focused \src{Dockable} using only the keyboard. The feature is activated as soon as \src{ctrl+shift+e} is pressed.
 \why A nice feature for people which do not like the mouse
\end{description}

\subsubsection{Extracting colors from LookAndFeel}
\begin{description}
 \short The mechanism to read colors from \src{LookAndFeel}s has been upgraded. Each \src{LookAndFeel} can now have its own specialized \src{LookAndFeelColors} that reads the colors.
 \why Allows to be more flexible with colors, allows the correct use of Nimbus and Windows.
\end{description}

\subsubsection{EclipseTheme}
\begin{description}
 \short \src{EclipseTheme} uses more colors from the \src{LookAndFeel}
 \why looks better
\end{description}

\subsubsection{SplitDockStation}
\begin{description}
 \short When dropping an element onto a \src{SplitDockStation}, the elements that are put aside receive at least a quarter of their original size.
 \why Sometimes the old elements shrunk too mutch.
\end{description}

\subsection{Bugfixes}
\subsubsection{Missing colors for BasicTheme}
\begin{description}
 \short \src{BasicTheme} did not update colors for the keys \src{paint.line}, \src{paint.divider} and \src{paint.division}. As a result some painting was not as in the older versions.
\end{description}

\subsubsection{Cutting bounds of children of SplitDockStation}
\begin{description}
 \short The bounds of children of \src{SplitDockStation} are now cut such that they are always within the stations boundaries.
 \why Rounding errors sometimes lead to little failures that made a single line of pixels invisible.
\end{description}

\subsubsection{NullPointerException when changing focus}
\begin{description}
 \short A \src{NullPointerException} could been thrown when the focus changed.
\end{description}

\subsubsection{Undecorated dialogs not undecorated}
\begin{description}
 \short When using \src{LookAndFeel}s that can draw window decorations on their own (like JTattoo), then \src{FlapWindow}, \src{ScreenDockDialog} and others\\could have decorations.
 \why The flag that advices the \src{LookAndFeel} not to paint a decoration was not set in the \src{JRootPane}s of these windows.
\end{description}

\subsubsection{RexTabbedComponent not adding/removing children}
\begin{description}
 \short \src{RexTabbedComponent} does no longer add and remove its children to change their visibility, it now uses a \src{CardLayout}.
 \why Some \src{Component}s did miss the change of the \src{LookAndFeel} when they were a child of \src{RexTabbedComponent}.
\end{description}

\subsubsection{Focusing a hidden CDockable}
\begin{description}
 \short When focusing a normalized \src{CDockable} that was hidden behind a maximized \src{CDockable}, then the focused dockable did not became visible.
 \why An old security system prevents change of the maximized element by the focus system.
\end{description}

\subsubsection{Missing events when changing state of CDockable}
\begin{description}
 \short When the \src{ExtendedMode} of a \src{CDockable} did not change because of a call of a special method, no state-change-events were fired.
 \why It was not intended that one action could change the state of many \src{CDockable}s.
\end{description}

\section{Version 1.0.6}
This version brings the preference system. The API was changed at some places in order to bring the preference system to work.

\subsection{Incompatibilities}
The changes that need special care.

\subsubsection{Dockable with Tooltip}
\begin{description}
 \short \src{Dockable} has a new method \src{getTitleToolTip}. \src{DockableListener} has a new method \src{titleToolTipChanged}.
 \why Allows to show a tooltip for a \src{Dockable} on titles and on tabs.
 \clients Must implement the two new methods.
\end{description}

\subsubsection{ColorManager generalized}
\begin{description}
 \short \src{ColorManager} extends \src{UIProperties}, \src{ColorProvider} is replaced by \src{ColorBridge} which extends \\\src{UIBridge}, \src{DockColor} extends \src{UIValue}. \\\src{ColorManager.getProviderFor} is replaced by \\\src{UIProperties.getBridgeFor}. Bridges and Values are no longer connected though the class of the \src{UIValue} but by a \src{Path} object. These objects are much more flexible than classes and not hard to understand.
 \why This generalization will allow to use the \src{UIProperties} for other things than just colors. There are plans to use the same system for fonts as well.
 \clients Should replace \src{ColorProvider} by \src{UIBridge}
\end{description}

\subsubsection{Resize Request in Common}
\begin{description}
 \short Size requests are now handled by \src{RequestDimension} and no longer with \src{Dimension}.
 \why Allows to issue requests only for with or for height.
 \clients Have to replace occurences of \src{Dimension} by \src{RequestDimension}.
\end{description}

\subsubsection{DockElementRepresentative}
\begin{description}
 \short \src{Dockable} and \src{DockTitle} implement the interface \\\src{DockElementRepresentative}
 \why Allows unified access to all \src{Component}s which are linked to a \src{Dockable}.
 \clients Have to implement the additional methods of \\\src{DockElementRepresentative}
\end{description}

\subsubsection{SimpleModifierMask deleted}
\begin{description}
 \short The class \src{SimpleModifierMask} has been removed. The interface \\\src{ModifierMask} has been changed to be
a class effectivly replacing \\\src{SimpleModifierMask}.
 \why This was necessary for the preference system. It was also unlikely that a client would ever implement \src{ModifierMask}.
 \clients Must replace \src{SimpleModifierMask} by \src{ModifierMask}.
\end{description}

\subsubsection{Map of DockThemes}
\begin{description}
 \short \src{CControl} has now a \src{ThemeMap}. This map contains \src{String}-\\\src{ThemeFactory} pairs. A new theme can be activated by calling \src{ThemeMap.select}.
 \why This is a simple representation of all the choices a user can do. The \src{CThemeMenuPiece} and the preference system can use the map to show choices and selection.
 \clients Instead of using \src{CControl.setTheme( DockTheme )} they should use \src{CControl.setTheme( String )}. Additinal \src{ThemeFactory}s have to be added directly to the \src{ThemeMap}, \src{CThemeMenuPiece} does no longer support inserting factories.
\end{description}

\subsubsection{Persistent storage of DockTheme}
\begin{description}
 \short The \src{DockTheme} of a \src{CControl} is no longer stored by the \\\src{CThemeMenuPiece} but directly by its \src{ThemeMap}.
 \why The \src{ThemeMap} is always present, the \src{CThemeMenuPiece} not. Hence if the \src{ThemeMap} is responsible for storing the theme, then the theme gets always stored.
 \clients Cannot do anything. The setting of the theme will be lost the next time the application starts and has to be set anew.
\end{description}



\subsection{API and Layout}
A list of new API elements and changes that affect the layout.

\subsubsection{Dropping onto SplitDockStation}
\begin{description}
 \short When dropping something onto a \src{SplitDockStation}, the old content always gets at least 25\% of the remaining space.
 \why In some situations the old content get no space and became invisible.
\end{description}

\subsubsection{UIProperties}
\begin{description}
 \short New \src{UIProperties}, a generalisation of \src{ColorManager}.
 \why Precondition to implement a similar system for fonts.
\end{description}

\subsubsection{Opened LockedResizeLayoutManager}
\begin{description}
 \short The private inner classes of \src{LockedResizeLayoutManager} have been made public and top level.
 \why Clients have better access and can better customize \\\src{LockedResizeLayoutManager}.
\end{description}

\subsubsection{ConflictResolver for locked resize}
\begin{description}
 \short The \src{ConflictResolver} in Common can now be used to resolve conflicts on resize when locked \src{CDockables} are around. Can be applied using the key \src{CControl.RESIZE_LOCK_CONFLICT_RESOLVER}.
 \why Developers wished to have the choice between different behaviors.
\end{description}

\subsubsection{FullLockConflictResolver}
\begin{description}
 \short A new \src{ConflictResolver} which is inspired by the behavior of VLDocking
 \why User request
\end{description}

\subsubsection{DockElementRepresentative}
\begin{description}
 \short New interface \src{DockElementRepresentative}. Creates a link between a \src{Component} and a \src{DockElement}.
 \why Gives a unified way to handle popup menus and drag and drop operations.
\end{description}

\subsubsection{Common: close-action and setVisible}
\begin{description}
 \short Clicking onto the close-action and calling \src{setVisible( false )} on a \src{CDockable} will now have the exact same effects.
 \why Seems to be reasonable that the close action just calls \src{setVisible}.
\end{description}

\subsubsection{Preference system}
\begin{description}
 \short A new system has been put in place to handle preferences. This new system is located in the package \src{bibliothek.extension.gui.dock}.
 \why This new system allows users to see and change various properties of the library. This includes things like the shortcuts for actions (like ctrl+m for maximizing a \src{Dockable}) or which colors are used by \src{BubbleTheme}. Future releases might contain more preferences.
\end{description}

\subsubsection{ColorScheme as property}
\begin{description}
 \short \src{BasicTheme} and subclasses read their \src{ColorScheme} from the \\\src{DockProperties}.
 \why a condition for the preference system
\end{description}

\subsubsection{Default locations in Common}
\begin{description}
 \short Clients can set the default location of a \src{Dockable} in Common. The method \src{setLocation} of \src{CStateManager} can be used for that. Also \\\src{AbstractCDockable} has a new method \src{setDefaultLocation} which can be used even if the element is not yet added to a \src{CControl}.
 \why user request.
\end{description}

\subsubsection{Borders on OverpaintablePanel}
\begin{description}
 \short \src{OverpaintablePanel} now supports \src{Border}s.
 \why Every \src{Component} should support \src{Border}s.
\end{description}

\subsubsection{SplitDockStation can disabled resizing}
\begin{description}
 \short Resizing on a \src{SplitDockStation} can be disabled.
 \why Requested by a user.
\end{description}

\subsubsection{Handle AWT components}
\begin{description}
 \short The \src{AWTComponentCaptureStrategy} can be used to create images from AWT components.
 \why AWT components cannot be handled like Swing components, the \\mechanism normally used created just a blank image.
\end{description}

\subsection{Bugfixes}

\subsubsection{DefaultConflictResolver did not respect locked sizes}
\begin{description}
 \short When several \src{ResizeRequest}s with different priority had to be handled, \src{DefaultConflictResolver} did not respect all of them. The algorithm has been fixed.
\end{description}

\subsubsection{Opening maximized CDockable}
\begin{description}
 \short When opening a \src{CDockable} which would stack on a maximized \\\src{CDockable}, then the layout could get scrambled. The solution is now to unmaximize any \src{CDockable}, then add the new element, then re-maximize the \src{CDockable}s.
\end{description}

\subsubsection{Dropping Dockable on SplitDockStation}
\begin{description}
 \short \src{Dockable}s can now be dropped onto \src{SplitDockStation}s which have size 0/0. In earlier versions the divider between \src{Dockable}s had a fixed size in pixels. Now the size of the divider is set to 0 if the \src{SplitDockStation} is too small. This prevents children to have negative sizes.
\end{description}

\subsubsection{CSplitLocation broken}
\begin{description}
 \short \src{CSplitLocation.expandProperty} did process the first element of a tree-path twice (thanks srcnick for fixing this bug).
\end{description}

\subsubsection{CStateManager.getLocation broken}
\begin{description}
 \short \src{CStateManager.getLocation} did return \src{null} when it should produce a result. There were also some \src{CLocation}s which did not return the correct result causing \src{getLocation} to fail.
\end{description}

\subsubsection{Stack-component of EclipseTheme broken}
\begin{description}
 \short When removing all elements of \src{EclipseStackDockComponent}, some elements could remain invisible.
\end{description}

\subsubsection{Change ColorScheme could throw NPE}
\begin{description}
 \short When updating the colors of a \src{BasicDockTheme} which was not installed, a \src{NullPointerException} was thrown.
\end{description}

\subsubsection{Items in popup-menu did do nothing}
\begin{description}
 \short Some \src{DockAction}s where not correctly wird when in a popup-menu. Clicking them would not result in any action (affects all \\\src{SelectableDockAction}s).
\end{description}

\section{Version 1.0.7}
Version 1.0.7 emphasizes on details. Many bugfixes are included and new settings allow further customization. The layout-storage mechanism has been improved to support missing dockables.

\subsection{Incompatibilities}
The changes that need special care.

\subsubsection{DockableDisplayerHints}
\begin{description}
 \short \src{Dockable} has a new method \src{configureDisplayerHints}.
 \why This allows \src{Dockable}s to communicate with their \src{DockableDisplayer}s. For example a \src{SplitDockStation} tells its displayer to paint a border if the station has no children, but not to paint a border if it has children.
 \clients If implementing \src{Dockable} directly need to add this method.
\end{description}

\subsubsection{ScreenDockDialog extends new class}
\begin{description}
 \short \src{ScreenDockDialog} extends other classes than before.
 \why The whole management of dialogs for \src{ScreenDockStation} has been rewritten. A \src{ScreenDockStation} now supports any kind of window, not only dialogs.
 \clients Should not be affected.
\end{description}

\subsubsection{DockFactory uses a new layer}
\begin{description}
 \short The whole layout-storage mechanism has been updated.
 \why To support missing dockables a new layer containing meta information was necessary.
 \clients The interface \src{DockFactory} contains new and changed methods
\end{description}

\subsubsection{CGridArea implements CDockable}
\begin{description}
 \short \src{CGridArea} is no longer just a panel but can also be used as dockable.
 \why In order to use \src{CGridArea} as superclass for \src{CWorkingArea} this interface was needed.
 \clients Should not affect clients.
\end{description}

\subsubsection{CWorkingArea extends CGridArea}
\begin{description}
 \short \src{CWorkingArea} is now a subclass of \src{CGridArea}.
 \why \src{CWorkingArea} and \src{CGridArea} have almost the same behavior. New interfaces and lesser coupling allowed to reuse \src{CGridArea}. In a future release they might even be merged into one class.
 \clients Most clients should not notify this change, clients that use code like \src{x instanceof CGridArea} need to be updated.
\end{description}

\subsubsection{CControlFactory: no longer creates CWorkingAreas}
\begin{description}
 \short \src{CControlFactory} no longer creates \src{CWorkingAreas} but \linebreak \src{SplitDockStation}s.
 \why This is part of an ongoing effort to lessen the coupling of classes in \src{Common}.
 \clients Clients that used a customized \src{CControlFactory} may need to update their factory.
\end{description}

\subsubsection{CommonDockable: getClose replaced with getSources}
\begin{description}
 \short In \src{CommonDockable} the method \src{getClose} was replaced with \linebreak \src{getSources}.
 \why This way a \src{CommonDockable} can support more than just one special \src{DockActionSource}. Also the close-action-source is no longer integrated that tight into the system.
 \clients Since clients should not work on this level anyway they don't need to worry.
\end{description}

\subsubsection{PropertyKey: requires factory for default value}
\begin{description}
 \short \src{PropertyKey} requires a \src{PropertyFactory} to set up its default value.
 \why Fixes a memory leak by preventing \src{PropertyKey} from sneaking in global variables.
 \clients Need to implement the factory if they create new \src{PropertyKey}s.
\end{description}

\subsection{API and Layout}
A list of new API elements and changes that affect the layout.

\subsubsection{Button-title supports colors}
\begin{description}
 \short The button-title on \src{FlapDockStation} can change its color, new keys for that feature are provided in \src{ColorMap}.
 \why Was just missing.
\end{description}

\subsubsection{FlapDockProperty: support state and size}
\begin{description}
 \short \src{FlapDockProperty} stores now holding state and window size as well.
 \why Allows clients more control over the layout, was necessary for \src{Common}.
\end{description}

\subsubsection{AdjacentDockFactory}
\begin{description}
 \short The \src{AdjacentDockFactory} can store additional information about a \src{Dockable} when writing a layout.
 \why Was required for \src{Common}.
\end{description}

\subsubsection{DockSituation: support for missing elements}
\begin{description}
 \short \src{DockSituation} has a number of new methods to support missing or invisible elements. The new methods are \src{fillMissing} and \linebreak \src{estimateLocation}s.
 \why Makes the user interface more consistent if missing elements are made available later.
\end{description}

\subsubsection{Support for gaps in layout}
\begin{description}
 \short \src{DockFrontend} now tries to fill missing gaps in the layout before a layout is applied.
 \why Makes the user interface more consistent if missing elements are made available later.
\end{description}

\subsubsection{Storing information of invisible dockables}
\begin{description}
 \short \src{DockFrontend} stores layout information of invisible/missing elements.
 \why Otherwise information would be lost and the user interface would seem inconsistant.
\end{description}

\subsubsection{Access to information of missing dockable}
\begin{description}
 \short New methods \src{listFrontendEntries} and \src{getFrontendEntry} in \linebreak \src{DockFrontend}.
 \why The methods allow access to all information of missing (and normal) \src{Dockable}s.
\end{description}

\subsubsection{PreferenceTable: order of operations reversed}
\begin{description}
 \short The order of ``default'' and ``remove'' operation are reversed.
 \why The ``default'' operation should be the last operation.
\end{description}

\subsubsection{Automatic stack creation in CGrid}
\begin{description}
 \short Eduardo Born suggested that if some dockables are placed at the same location in a \src{CGrid} then they should be put together in a stack.
 \why There is no reason not to do it this way.
\end{description}

\subsubsection{Central register for CDockables}
\begin{description}
 \short \src{CControl} stores all its stations and dockables now in a \linebreak \src{CControlRegister}.
 \why New classes are introduced to free \src{CControl} of minor tasks.
\end{description}

\subsubsection{FontManager}
\begin{description}
 \short New methods to change the fonts on titles and tabs. The interface \src{DockFont} provides some keys that can be used together with \linebreak \src{FontManager}.
 \why That's a feature every docking-framework should have
\end{description}

\subsubsection{FontMap}
\begin{description}
 \short \src{Common} supports the new font system, the \src{FontMap} can be used like the \src{ColorMap}.
 \why Because \src{Core} allows this.
\end{description}

\subsubsection{More than one maximize-area}
\begin{description}
 \short In \src{Common} more than only one station can now be marked as being potential parent of a maximized \src{CDockable}.
 \why Part of ongoing work for less coupling in \src{Common}.
\end{description}

\subsubsection{Veto before changing layout}
\begin{description}
 \short The method \src{hiding} of \src{VetoableDockFrontendListener} is called when setting a new layout.
 \why Prevents dockables to disappear that must always be visible
\end{description}

\subsubsection{CGrid/SplitDockGrid: preselect element}
\begin{description}
 \short \src{CGrid}/\src{SplitDockGrid} have a new method \src{select}/\src{setSelected} to select a \src{CDockable}/\src{Dockable} in a stack of dockables.
 \why More control over the layout.
\end{description}

\subsubsection{WindowProviders}
\begin{description}
 \short New interface \src{WindowProvider} allows to change the root-window even after the framework runs.
 \why Some clients do not know their root window when setting up a controller, other clients did have a hard time to find the root-\src{JFrame} (like applets, which do not have such a frame).
\end{description}

\subsubsection{AppletWindowProvider}
\begin{description}
 \short A new \src{WindowProvider} is available, the \src{AppletWindowProvider}.
 \why This class supports \src{Applet}s by finding the (normally hidden) window on which the applet lies.
\end{description}

\subsubsection{LocaleListener}
\begin{description}
 \short The new \src{LocaleListener} can be added to \src{DockUI} and will be informed if the \src{Locale} changes.
 \why Internal caches of \src{Common} can be cleaned through this listener.
\end{description}

\subsubsection{DockController: freeze layout}
\begin{description}
 \short \src{DockController} has new methods \src{freezeLayout}, \src{meltLayout} and \linebreak \src{isLayoutFrozen}.
 \why These methods temporarily freeze the layout so clients can safely add and remove \src{Dockable}s from the tree. Prevents the \src{SingleParentRemover} to do its work and change the tree at the same time.
\end{description}

\subsection{Bugfixes}
\subsubsection{SplitDockStation not respecting acceptances}
\begin{description}
 \short On a \src{SplitDockStation} a \src{Dockable} could be dropped over another element which didn't accept that combination.
\end{description}

\subsubsection{Common and CGrid: not supporting big stacks}
\begin{description}
 \short When dropping \src{CGrid} with stacks that have 3 or more elements, then an exception was thrown.
\end{description}

\subsubsection{DockFrontend did not read setting correctly}
\begin{description}
 \short The method \src{read} of \src{DockFrontend} did mark the main setting as simple entry while it should have been marked as main entry.
\end{description}

\subsubsection{Infinite recursion in focus raversal}
\begin{description}
 \short \src{DockFocusTraversalPolicy} would create an infinite recursion when used together with \src{javax.swing.LegacyGlueFocusTraversalPolicy}.
\end{description}

\subsubsection{CWorkingArea not settings itself as working-area}
\begin{description}
 \short The method \src{deploy} of \src{CWorkingArea} did not inform the children that they are now child of a working-area.
\end{description}

\subsubsection{SplitDockGrid throwing exception}
\begin{description}
 \short When the same coordinates were used twice or more for putting elements in a \src{SplitDockGrid} an exception was thrown.
\end{description}

\subsubsection{FlapWindow not resizing}
\begin{description}
 \short A \src{FlapWindow} did not always resize correctly when its parent got resized while the window was invisible. Fixed by Peter.
\end{description}

\subsubsection{Dropping \src{CWorkingArea}}
\begin{description}
 \short Dropping a \src{CWorkingArea} that has children did not work.
\end{description}

\subsubsection{Drop CDockable with no location but working-area}
\begin{description}
 \short A \src{CDockable} that has not set any location but belongs to a working-area will now use the default location for that working-area.
\end{description}

\subsubsection{AbstractCDockable ignores settings}
\begin{description}
 \short \src{AbstractCDockable} did not respond when setting an extended mode and another extended mode was disabled. The cause of this failure was a missing ``break'' in a ``switch'' statement.
\end{description}

\subsubsection{SecureScreenDockStation not secure}
\begin{description}
 \short \src{SecureScreenDockStation} was not using \linebreak \src{SecureScreenDockWindowFactory}.
\end{description}

\subsubsection{Exception in updateLocation}
\begin{description}
 \short The method \src{updateLocation} of \src{DockFrontend} would throw an exception if a \src{Dockable} in the tree was at the same time a root-station.
\end{description}

\subsubsection{Buttons on CDockable}
\begin{description}
 \short When a minimzed \src{CDockable} was closed and then made visible again its extension-mode-buttons were not correctly set.
\end{description}

\section{Version 1.0.8}
This version brings many new feautures: the \src{CLocationModeManager} handles the location of \src{CDockable}s, placeholders store the location of \src{Dockable}s much more precise than the old system, tabs can be placed at any side.

The changes are ordered by the time when they were introduced.

\subsection{Incompatibilities}
The changes that need special care.

\subsubsection{DockableDisplayerListener}
\begin{description}
 \short \src{DockableDisplayer}s can now be observed by \linebreak \src{DockableDisplayerListeners}.
 \why This allows a \src{DockableDisplayer} to mark itself as obsolete, \linebreak \src{DockStations} then can create new displayers.
 \clients Any class that uses \src{DockableDislayer}s should add the listener and react on its events.
\end{description}

\subsubsection{EclipseThemeConnectorListener}
\begin{description}
 \short \src{EclipseThemeConnector} can be observed by a \linebreak \src{EclipseThemeConnectorListener}.
 \why This allows to change properties even after asking the connector for them
 \clients Clients implementing a \src{EclipseThemeConnector} have to call the listener
\end{description}

\subsubsection{FocusObserver: veto}
\begin{description}
 \short Focus transfer when clicking the mouse can now be canceled. The \src{MouseFocusObserver} calls a methode \src{handleVeto} which cancels an event.
 \why A feature request by a user, should be used with care.
 \clients The new \src{FocusVetoListener} can be added to the focus observer and allows clients to cancel focus transfer.
\end{description}

\subsubsection{DockProperties: priority}
! API: DockProperties now supports different priorities for values, "default", "theme" and "client".
\begin{description}
 \short \src{DockProperties} now stores properties with different priorities. ``Client'' overrides ``theme'', ``theme'' overrides ``default''.
 \why Allows \src{DockTheme}s and clients to use the properties together.
 \clients Should always register their properties with priority ``client''.
\end{description}

\subsubsection{CLocationModeManager}
\begin{description}
 \short \src{CStateManager} got replaced by \src{CLocationModeManager}.
 \why The \src{CLocationModeManager} is built much more generic than \linebreak \src{CStateManager} allowing new \src{DockStation}s and new extended-modes.
 \clients The method \src{CControl.getStateManager} was renamed to \linebreak \src{getLocationManager}.
\end{description}

\subsubsection{SplitDockStation: leaf id}
\begin{description}
 \short Each node of a \src{SplitDockStation} has now a unique identifier.
 \why This identifier is used to store the location of a \src{Dockable}.
 \clients This is a change in the internal API, clients are not affected.
\end{description}

\subsubsection{DockTitleRequest}
\begin{description}
 \short \src{DockTitleFactory} has been changed. Now a \src{DockTitleRequest} is installed on the factory, the factory may trigger this request anytimes (also more than once). The new class \src{StationChildHandle} manages the interaction between \src{Dockable}, \src{DockableDisplayer}, \src{DockTitle} and \src{DockTitleRequest}.
 \why The API is now much more consistent. Also anyone knowing a \linebreak \src{DockTitleRequest} can update/replace the title at any time.
 \clients Please read chapter 5 ``Titles'' of the guide for Core.
\end{description}

\subsubsection{DockFrontend: methods moved}
\begin{description}
 \short Some methods of \src{DockFrontend} have been moved to \linebreak \src{DefaultLayoutChangeStrategy}.
 \why Allows \src{Common} to handle its special needs, e.g. to reuse \linebreak \src{MultipleCDockable}s when the layout changes.
 \clients This API was used internally, clients should not be affected.
\end{description}

\subsubsection{Placeholders}
\begin{description}
 \short Placeholders remain at the position where a \src{Dockable} was removed. The feature is implemented in \src{Core} but only activated if \src{Common} is used.
 \why This makes location information much more resilient against failures due to missing \src{Dockable}s.
 \clients May need to implement a \src{PlaceholderStrategy} if they want to use placeholders in \src{Core}. All existing layout information will be upgraded automatically. It is not possible for an old version of DockingFrames to read a layout written with 1.0.8.
\end{description}

\subsubsection{EclipseTheme respects settings of StackDockStation}
\begin{description}
 \short \src{BaseTabComponent} is no longer responsible for keeping icon and text up to date, this must be handled by the \src{StackDockComponent}. 
 \why This means that the \src{EclipseTheme} now respects the text and icon set by the \src{StackDockStation}
 \clients This API was used internally, clients should not be affected by these changes
\end{description}



\subsection{API and Layout}
A list of new API elements and changes that affect the layout.
\subsubsection{EclipseTheme, no-title and tabs}
\begin{description}
 \short New \src{CommonEclipseThemeConnector} ensures that \src{CDockable} with no title do not have a tab if not necessary in the \src{EclipseTheme}.
 \why Since tabs are used like titles in the \src{EclipseTheme}, they also should be hidden if the no-title property is set.
\end{description}

- API: new CVetoFocusListener in Common, can speak a veto for some focus changes
\subsubsection{CVetoFocusListener}
\begin{description}
 \short A new \src{CVetoFocusListener} can be added to \src{CControl}.
 \why The listener can be used to cancel focus changes, should be used with care.
\end{description}

\subsubsection{SingleTabDecider}
\begin{description}
 \short The interface \src{SingleTabDecider} allows \src{Dockable}s to be displayed with a tab, even if a tab is not necessary.
 \why Creates a new look and a new feeling if combined with a no-title feature.
\end{description}

\subsubsection{CDockable single-tab}
\begin{description}
 \short \src{CDockable} has a new property \src{singleTabShown} which is forwarded to a \src{SingleTabDecider}
 \why Allows clients to enabled/disable single tabs for each \src{CDockable} individually.
\end{description}

\subsubsection{Tab placement}
\begin{description}
 \short New property \src{StackDockStation.TAB\_PLACEMENT} globally sets where to put tabs. Must be supported by the current \src{TabLayoutManager}.
 \why Allows clients more customization.
\end{description}

\subsubsection{TabLayoutManager}
\begin{description}
 \short New class \src{TabLayoutManager} to handle the positioning of tabs on a \src{StackDockStation}.
 \why Decoupling of looks (tabs) and logic (their position). 
\end{description}

\subsubsection{CPanelPopup}
\begin{description}
 \short New action \src{CPanelPopup} in \src{Common} provides an easy way to create a popup-action with an arbitrary \src{Component} as content.
 \why Allows more customization.
\end{description}

\subsubsection{Access to actions of CDockable}
\begin{description}
 \short \src{CDockable} has new methods \src{getAction} and \src{getActionCount} to access \src{CAction}s that were added. 
 \why Clients no longer have to remember what actions they added.
\end{description}

- API: 
\subsubsection{Minimum size on FlapDockStation}
\begin{description}
 \short New key \src{FlapDockStation.MINIMUM\_SIZE} sets the default minimum size of \src{FlapDockStation}s.
 \why To make sure a \src{Dockable} does not get too small.
\end{description}

\subsubsection{CContentArea.setMinimumAreaSize}
\begin{description}
 \short \src{CContentArea.setMinimumAreaSize} set the minimum size of minimized \src{CDockable}s.
 \why To make sure a \src{CDockable} does not get too small.
\end{description}

\subsubsection{AbstractDockable: KeyListener}
\begin{description}
 \short \src{AbstractDockable} has new method \src{add/removeKeyListener}.
 \why Allows to observe any \src{KeyEvent} that is related to a \src{Dockable}. Children of dockable \src{DockStation}s are ignored.
\end{description}

\subsubsection{CVetoClosingListener}
\begin{description}
 \short A \src{CVetoClosingListener} can be added to \src{CControl} or \src{CDockable}.
 \why The listener is called before a \src{Dockable} or a set of \src{Dockable}s is closed. The listener may cancel the operation.
\end{description}

\subsubsection{AbstractCDockable: createCommonDockable}
\begin{description}
 \short \src{AbstractCDockable} has a new method \src{createCommonDockable}.
 \why Clients can override the method and thus customize the \src{Dockable} which represents the \src{CDockable}.
\end{description}

\subsubsection{Merger}
\begin{description}
 \short The interface \src{Merger} allows two \src{DockStation}s to be merged automatically.
 \why The implementation \src{StackMerger} merges to \src{StackDockStation}s. \linebreak This allows to drag a stack of \src{Dockable}s at a new location.
\end{description}

\subsubsection{StackDockStation: single tab}
\begin{description}
 \short A \src{StackDockStation} with only one child can still show a tab depending on the type of \src{StackDockComponent}
 \why A feature request by a developer.
\end{description}

- API: ScreenDockStation now supports fullscreen mode for its children. What "fullscreen" means can be influenced by a ScreenDockFullscreenStrategy.

\subsubsection{ScreenDockStation: fullscreen mode}
\begin{description}
 \short \src{ScreenDockStation} now supports fullscreen mode for its children. The exact meaning of ``fullscreen'' is defined by a \linebreak \src{ScreenDockFullscreenStrategy}.
 \why Because it was really missing.
\end{description}

\subsubsection{TabContentFilter}
\begin{description}
 \short The new interface \src{TabContentFilter} tells the framework what to show on a tab.
 \why Allows some more customization, e.g. show only short titles.
\end{description}

\subsubsection{FlapDockStation: factory}
\begin{description}
 \short \src{FlapDockStation} supports factory for creating the window 
 \why To use \src{FlapDockStation} on a \src{JInternalFrame}.
\end{description}

\subsubsection{StackDockComponent: default representation}
\begin{description}
 \short \src{StackDockComponent} now offers a method \linebreak \src{createDefaultRepresentation}.
 \why This allows code to be executed when clicking on, or dragging of, an empty space arounds tabs.
\end{description}

\subsubsection{DropDownMenu: selection if submenu}
\begin{description}
 \short Clicking on a child action of a \src{DropDownAction} that is shown as submenu now changes the selection of the button as well.
 \why That is the expected behavior.
\end{description}

\subsubsection{SplitDockFullScreenProperty}
\begin{description}
 \short New property \src{SplitDockFullScreenProperty}.
 \why This property points to a fullscreen \src{Dockable} on a \src{SplitDockStation} and can be used to merge that element with another \src{Dockable}.
\end{description}

\subsubsection{CMaximizedLocation}
\begin{description}
 \short Extends now \src{AbstractStackholdingLocation}.
 \why Allows to combine a maximized \src{Dockable} with another \src{Dockable}
\end{description}

\subsubsection{OrientationToRotationStrategy}
\begin{description}
 \short New interface \src{OrientationToRotationStrategy}.
 \why The strategy allows clients to specify how to rotate text on a \src{DockTitle}
\end{description}

\subsection{Bugfixes}
\subsubsection{EclipseStackDockComponent: Exception}
\begin{description}
 \short \src{EclipseStackDockComponent} contained an unnecessary and not correctly updated list of \src{Dockable}s causing an \src{IndexOutOfBoundsException} on JREs of version 1.5.0\_12 or higher.
\end{description}

\subsubsection{AWT and Glass-Pane}
\begin{description}
 \short Workaround for bug \url{http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6797587} , AWT components not painted properly if behind a glass-pane.
\end{description}

\subsubsection{Check before drop}
\begin{description}
 \short \src{DockStation}s check whether dropping some \src{Dockable} would create an invalid \src{Component}-tree, and forbid such drag and drop operations
 \end{description}

\subsubsection{SimpleDockACtion: unbinding}
\begin{description}
 \short \src{SimpleDockAction} did not unbind itself correctly due of events fired in an unfortunate order. Repaired thanks to an anonymous user.
\end{description}

\subsubsection{StackDockStation: reselect}
\begin{description}
 \short When making a selected \src{Dockable} on a \src{StackDockStation} invisible, a new \src{Dockable} should be properly selected.
\end{description}

\subsubsection{RequestDimension: constructor}
\begin{description}
 \short \src{RequestDimension( int, boolean )} did not set the height property.
\end{description}

\subsubsection{MultiDockActionSource: exception}
\begin{description}
 \short Wrong index in \src{MultiDockActionSource.add( DockActionSource )} could lead to \src{IndexOutOfBoundsException}.
\end{description}

\subsubsection{SplitDockStation: cursor}
\begin{description}
 \short Cursor on the \src{SplitDockStation} sometimes does not change from arrow to default cursor. Should happen less often now, patch by Eduardo Born.
\end{description}

\subsubsection{FlatTab: mouse events}
\begin{description}
 \short \src{FlatTab} did not react on mouse-dragged events if in a "secure environment".
\end{description}

\subsubsection{StackDockStation: not removed}
\begin{description}
 \short \src{StackDockStation} was not always removed if it had only one child \linebreak and this one child was a \src{CDockable} associated with a \src{CWorkingArea}.
\end{description}

\subsubsection{FlapDockStation: exception on move}
\begin{description}
 \short Moving a \src{Dockable} on a \src{FlapDockStation} did throw an exception if the destination index was too big.
\end{description}

\subsubsection{Location of missing CDockable}
\begin{description}
 \short If a \src{CDockable} is removed and the \src{CMissingDockableStrategy} tells to store information about that \src{Dockable}, then its location remains now stored.
\end{description}

\subsubsection{Tabs: wrong size}
\begin{description}
 \short If \src{TabPlacement} was ``left'' or ``right'', then new tabs in a \linebreak \src{StackDockStation} could be too big. Reason for this bug was that new tabs were not properly initialized and assumed that \src{TabPlacement} was ``top''.
\end{description}

\subsubsection{Tabs: missing tabs}
\begin{description}
 \short \src{StackDockStation} did not add its children correctly to the \linebreak \src{StackDockComponent}, leading to some missing tabs
\end{description}

\subsubsection{Exception on normalizing}
\begin{description}
 \short Normalizing a externalized \src{CDockable} could throw an Exception
\end{description}


\subsubsection{StackDockStation: move}
\begin{description}
 \short \src{StackDockStation} could not be moved around in Common even if children would allow it.
\end{description}

\subsubsection{Placeholders: missing}
\begin{description}
 \short Dragging a station away from another station did not store placeholders
\end{description}

\subsubsection{StackDockStation: selection changes}
\begin{description}
 \short During drag and drop, dragging the mouse over a tab of a \linebreak \src{StackDockStation} could exchange the selected \src{Dockable}.
\end{description}

\subsubsection{ScreenDockStation: exception}
\begin{description}
 \short Dragging a \src{Dockable} over a child of a \src{ScreenDockStation} could throw an exception (in \src{Common}).
\end{description}


\subsubsection{StackDockStation: no event}
\begin{description}
 \short \src{StackDockStation} did not fire dockable-selected event properly when using the \src{DefaultStackDockComponent}.
\end{description}

\subsubsection{Tabs: strange position}
\begin{description}
 \short Tabs with unequal height were positioned strangely.
\end{description}

\subsubsection{DefaultStackDockComponent: popup menus}
\begin{description}
 \short Popup menus are now enabled for tabs on a \linebreak \src{DefaultStackDockComponent}
\end{description}

\subsubsection{DockRegister: missing events}
\begin{description}
 \short If \src{DockRegister} was stalled and a \src{DockStation} was added/removed to the register and later \src{Dockables} added/removed from that station, then the \src{DockRegister} could miss these modifications and store too many/few \src{Dockables}.
\end{description}


\subsubsection{CActionSource: missing events}
\begin{description}
 \short \src{CActionSource} did not fire events when removing or replacing actions
\end{description}
 
\subsubsection{CLocationModeManager: exception}
\begin{description}
 \short \src{CLocationModeManager.setLocation} did not compare the correct objects and has always thrown an exception.
\end{description}

\subsubsection{Corner components: wrong location}
\begin{description}
 \short Minimized \src{CDockables} did not appear at the correct location if corner components were used
\end{description}

\subsubsection{Maximized CDockable: exception}
\begin{description}
 \short Dragging a maximized \src{CDockable} could throw an exception
\end{description}


\subsubsection{BasicStackDockComponent: exception}
\begin{description}
 \short Dragging a tab from a \src{BasicStackDockComponent} could throw an exception
\end{description}

\subsubsection{Path: wrong encoding}
\begin{description}
 \short \src{Path} did not encode non-java identifiers right.
\end{description}

\subsubsection{EclipseMenu: update icon}
\begin{description}
 \short \src{EclipseMenu} did not update its icon automatically
\end{description}

\subsubsection{StackDockStation: move}
\begin{description}
 \short \src{StackDockStation.move(Dockable,DockableProperty)} could throw \linebreak exception if destination index was too big.
\end{description}


\subsubsection{AbstractScreenDockWindow: wrong update}
\begin{description}
 \short \src{AbstractScreenDockWindow.setDockable} did call \src{updateTitleIcon} instead of \src{updateTitleText}.
\end{description}

\subsubsection{DockTitleTab: exception}
\begin{description}
 \short \src{DockTitleTab} caused exception when uninstalled
\end{description}


\subsubsection{PropertyPreference: load default}
\begin{description}
 \short Instead of doing nothing, \src{PropertyPreferences} now load their default value if they cannot read any other value.
\end{description}

\subsubsection{CGrid: missing Dockables}
\begin{description}
 \short When deploying a \src{CGrid} some \src{Dockables} did not appear: the tree of the \src{SplitDockStation} was cleaned up too early before all \src{Dockable}s had been inserted, leading to a corrupted tree.
\end{description}

\subsubsection{SplitDockStation: wrong id}
\begin{description}
 \short \src{SplitDockStation} did assign leaf-id to node when using \linebreak \src{drop(SplitDockPathProperty)}. As a result unmaximizing a stack of \src{CDockables} could destroy the stack.
\end{description}

\subsubsection{SplitDockStation: update layout}
\begin{description}
 \short \src{SplitDockStation} does now always update the boundaries of its tree before dropping a \src{Dockable}. Wrong boundaries did lead to \src{Dockable}s dropped at the wrong location even if the used \src{DockableProperty} was correct.
\end{description}

\subsubsection{Path: encoding}
\begin{description}
 \short \src{Path} now encodes its content when using \src{toString} and decodes contents on creation. Meaning inside a \src{Path} object the items are never encoded.
\end{description}

\subsubsection{MouseFocusObserver: request focus}
\begin{description}
 \short \src{MouseFocusObserver} no longer calls \src{requestFocusInWindow} if a \linebreak \src{Component} does not belong to a \src{Dockable}
\end{description}

\subsubsection{SplitDockStation: placeholders}
\begin{description}
 \short \src{SplitDockStation} is now much more strict when it comes to enforcing the uniqueness of placeholders
\end{description}

\subsubsection{Dockable CStation issue}
\begin{description}
 \short If a \src{CStation} was registered at a \src{CControl} and later the same object was registered as a \src{SingleCDockable}, then \src{CControl} did not assign a unique identifier to that Station/Dockable. 
\end{description}

\subsubsection{SimpleDockAction: memory leak}
\begin{description}
 \short \src{SimpleDockAction.KeyForwarder} caused a memory leak by not removing its listeners properly.
\end{description}

\subsubsection{CLocation: null root}
\begin{description}
 \short \src{CLocation}s returning \src{null} as root but having an \src{ExtendedMode} are (again) supported.
\end{description}

\subsubsection{SplitDockStation: locked size}
\begin{description}
 \short When moving/dragging a \src{Dockable} from a \src{SplitDockStation} with size-locked \src{Dockable}s, the locked \src{Dockable}s got resized even if it was not necessary.
\end{description}

\subsubsection{DockUI: stalls events}
\begin{description}
 \short \src{DockUI} now stalls all events rather than setting the \linebreak \src{SingleParentRemover} to \src{null} when updating the \src{DockTheme} of a station.
\end{description}


\subsubsection{CLayoutChangeStrategy: exception}
\begin{description}
 \short \src{CLayoutChangeStrategy.replaceMultipleDockables} could throw a \linebreak \src{NullPointerException}.
\end{description}

\subsubsection{CDockable: base location}
\begin{description}
 \short \src{CDockable.getBaseLocation} did return \src{null} when a location was actually available
\end{description}

\subsubsection{Glass Extension}
\begin{description}
 \short Glass Extension no longer throws Exception if width or height of tab is equal to 0.
\end{description}

\subsubsection{SplitDockStation: cursor}
\begin{description}
 \short Cursor should no longer remain arrow when moved away from a divider of a \src{SplitDockStation}.
\end{description}

\section{Version 1.1.0}
From this version on only incompatible changes will be listed in the document. The compatible changes and bugfixes either do not affect clients, or can be found in the \src{changes.txt} file already.
\subsection{Incompatibilities}

\subsubsection{SincleCDockableBackupFactory}
\begin{description}
 \short \src{SingleCDockableBackupFactory} was replaced by the new \linebreak \src{SingleCDockableFactory}.
 \why There is no reason to call it a ``backup'' factory anymore. It is now just a factory like any other factory.
 \clients Have to replace the interface wherever it appears, the methods remain the same.
\end{description}

\subsubsection{Interface Combiner updated}
\begin{description}
 \short The interface \src{Combiner} has been completely rewritten.
 \why The \src{Combiner} has now much more control of how two \src{Dockable}s are going to be merged. It can even paint on the \src{DockStation} during a drag and drop operation.
 \clients Any implementation of \src{Combiner} has to be implemented anew from scratch.
\end{description}

\subsubsection{PlaceholderList update}
\begin{description}
 \short \src{PlaceholderList} is now abstract and has more generic arguments.
 \why This allows subclasses which are used by the API for perspectives.
 \clients Can use \src{DockablePlaceholderList} instead of \src{PlaceholderList}.
\end{description}

\subsubsection{DockFactory has new methods}
\begin{description}
 \short \src{DockFactory} has additional methods and new generic arguments.
 \why All these changes are to support the perspective API.
 \clients Can either ignore the new methods (e.g. always return \src{null}) or have to implement the new methods if they want to use perspectives.
\end{description}

\subsubsection{Various new generic parameters and abstractions}
\begin{description}
 \short Various classes and interfaces have new generic parameters and/or were made abstract.
 \why These changes where necessary in order to support the new perspective API.
 \clients Can either ignore the changes if they do not use the perspective API, or implement missing parts. However, most clients should not notice these changes as they were made in a layer that is not accessed by most clients.
\end{description}

\subsubsection{Working-area set during loading}
\begin{description}
 \short Common now stores the identifier of the working-area which owns a \src{SingleCDockable} and changes the working-area property when loading a layout.
 \why This was required by the perspective API, otherwise working-areas could not have been supported.
 \clients Should not be affected by this change as clients normally do not change the working-area of a \src{Dockable}.
\end{description}

\subsubsection{UIProperties depend on UIScheme}
\begin{description}
 \short \src{UIProperties} now depend on \src{UIScheme}.
 \why \src{UIScheme}s are a good way set the default values of an \src{UIProperties}. The mechanism was first introduced for the \src{ColorManager} but is now generalized.
 \clients The API of the \src{ColorScheme} has changed and clients may need to reimplemented classes based on \src{ColorScheme}.
\end{description}

\subsubsection{Introducing ThemeManager}
\begin{description}
 \short The importance of the interface \src{DockTheme} has much decreased.
 \why The new \src{ThemeManager} allows clients to override properties related to a \src{DockTheme} without the need to access the \src{DockTheme}.
 \clients Clients will not notice any change as the API for \src{DockTheme} remaines unchanged. However, developers should be aware of the \src{ThemeManager} which is much more convenient to use then subclassing \src{DockTheme}s.
\end{description}
 
\subsubsection{``secure'' classes obsolete}
\begin{description}
 \short All ``secure'' classes are obsolete, instead the property ``restricted environment'' in \src{DockController} is to be used.
 \why This change reduces complexity as the same code can now be used in a standard application and in an unsigned applet.
 \clients The old classes have been marked \src{deprecated}, clients should remove any references to the old ``secure`` classes.
\end{description}
 
\subsubsection{SplitDockStationFactory}
\begin{description}
 \short \src{SplitDockStationFactory} now stores whether a \src{SplitDockStation} did have a fullscreen-action or not.
 \why Otherwise the setting could be corrupted when loading a layout.
 \clients Should treat this like a bugfix.
\end{description}

\subsubsection{Renaming in focus API}
\begin{description}
 \short Renamed: \src{FocusController} to \src{VisibilityFocusObserver}, \linebreak \src{DockController.getFocusObserver} to \src{getMouseFocusObserver} and \linebreak added new interface \src{FocusController}.
 \why Part of an ongoing effort to hide all controller-classes behind interfaces.
 \clients Most clients are not affected. Clients implementing a focus system have to use the new interface.
\end{description}

\subsubsection{FocusVetoListener added to FocusController}
\begin{description}
 \short \src{FocusVetoListener} is now added to \src{FocusController} instead of \linebreak \src{MouseFocusObserver}.
 \why Part of an ongoing effort to hide all controller-classes behind interfaces. Also the listener is now asked more often for a veto.
 \clients May need to replace references to \src{MouseFocusObserver} by references to \src{FocusController}.
\end{description}

\subsubsection{ButtonContent is now a class}
\begin{description}
 \short The enum \src{ButtonContent} is now a class.
 \why The new class allows much finer control of what is to be displayed on a \src{FlapDockStation}
 \clients The old constants remain available, clients have to update their \src{import} statements  since \src{ButtonContent} is now a top-level class.
\end{description}

\subsubsection{ButtonContentPreference replaced}
\begin{description}
 \short \src{ButtonContentPreference} got replaced by the new \linebreak \src{ButtonContentPreferenceModel}.
 \why Because the \src{ButtonContent} class now offers much more options that before.
 \clients Have to update any reference to \src{ButtonContentPreference}.
\end{description}

\subsubsection{IconManager and DockIcon}
\begin{description}
 \short The \src{IconManager} now extends \src{UIProperties}.
 \why Allows much more control over the icons.
 \clients All icons have now to be accessed through a \src{DockIcon}, direct access of the icons is deprecated.
\end{description}

\subsubsection{IconManager handles all icons}
\begin{description}
 \short All icons are now handled by the \src{IconManager}, \src{DockUI} and \src{Resources} are no longer handling any icons.
 \why This more centralized approach makes customization of icons much easier.
 \clients Any access to icons has now to go through the \src{IconManager}.
\end{description}

\subsubsection{Unique identifiers of SplitNodes}
\begin{description}
 \short The unique identifier of a \src{SplitNode} may change if a new child is added to the tree.
 \why Required in order to resolve collisions of identifiers.
 \clients Clients should not treat the unique identifier as a constant.
\end{description}

\subsubsection{TextManager}
\begin{description}
 \short All the text that appears on buttons/titles/etc. is now handled by the \src{TextManager}.
 \why This allows clients to modify the text, or even load additional language packages.
 \clients Any access to text has now to go through the \src{TextManager}.
\end{description}

\subsubsection{DockStationListener updated}
\begin{description}
 \short \src{DockStationListener} has an additional method \linebreak \src{dockableRepositioned}.
 \why Allows the framework and clients to better keep track of the location of a \src{Dockable}.
 \clients Any class implementing \src{DockStationListener} has to implement the new method. Any class implementing \src{DockStation} has to invoke the new method.
\end{description}

\subsubsection{Class Resources removed}
\begin{description}
 \short The class \src{Resources} has been removed.
 \why Icons are now handled by the \src{IconManager}, text is now handled by the \src{TextManager} and the default bundle is now loaded in \src{CControl.initTexts} using a \src{DefaultTextScheme}.
 \clients Must use \src{IconManager} and \src{TextManager} instead.
\end{description}

\subsubsection{CDockableStateListener updated}
\begin{description}
 \short \src{CDockableStateListener} no longer has one method for each \linebreak \src{ExtendedMode}, instead one method handles all possible \src{ExtendedMode}s.
 \why This keeps the option of new \src{ExtendedMode}s open.
 \clients Clients can extend \src{CDockableAdapter} to keep the old API.
\end{description}

\subsubsection{DockSituation uses two PlaceholderStrategies}
\begin{description}
 \short \src{DockSituation} can now use a \src{PlaceholderStrategy} to load the intermediate format and another strategy to load the final \src{DockElement}s.
 \why Allows more flexibility.
 \clients May need to set the \src{PlaceholderStrategy} twice in order to have the desired effect.
\end{description}

\subsubsection{DockRelocator updated}
\begin{description}
 \short \src{DockRelocator} has two additional methods \src{getRemote} and \linebreak \src{getDirectRemote} with a parameter \src{forceDrag}.
 \why Allows clients to force start a drag and drop operation.
 \clients Clients implementing the \src{DockRelocator} interface need to implement the new methods as well.
\end{description}

\subsubsection{New CGroupMovement}
\begin{description}
 \short \src{CGroupBehavior} now creates a \src{CGroupMovement} instead of executing its changes directly.
 \why Allows to reuse existing code much easier.
 \clients Clients implementing a \src{CGroupBehavior} may now need to implement a \src{CGroupMovement} as well.
\end{description}

\subsubsection{CMaximizedBehavior removed}
\begin{description}
 \short \src{CMaximizedBehavior} and all associated methods have been removed.
 \why All the functionality of \src{CMaximizeBehavior} is now implemented by the \src{CGroupBehavior}.
 \clients Clients implementing a \src{CMaximizedBehavior} must now implement a \src{CGroupBehavior} instead.
\end{description}

\subsubsection{DockUI updated}
\begin{description}
 \short Several methods of \src{DockUI} have been removed, this includes the \linebreak \src{LocaleListener}.
 \why This functionality was replaced by the \src{ThemeManager} and the \linebreak \src{TextManager}.
 \clients Have to use the managers instead of \src{DockUI}.
\end{description}

\subsubsection{Methods renamed in StackDockComponentParent}
\begin{description}
 \short Some methods in StackDockComponentParent renamed.
 \why Prevents conflicts with methods in other interfaces that have the same signature but different usage.
 \clients Must rename these methods as well.
\end{description}

\subsubsection{CControlFactory updated}
\begin{description}
 \short \src{CControlFactory} now creates \src{CommonStation} instead of \src{DockStation}s.
 \why All \src{DockStation}s used by a \src{CStation} now implement the interface \src{CommonStation}.
 \clients Clients implementing \src{CControlFactory} have to implement the new methods as well.
\end{description}

\subsubsection{CommonStation updated}
\begin{description}
 \short \src{CommonStation} no longer extends \src{CommonDockable}.
 \why Because not every \src{DockStation} is to be treated like a \src{Dockable}.
 \clients Any code assuming that a \src{CommonStation} is a \src{CommonDockable} has to be updated.
\end{description}

\subsubsection{New interface CommonElement}
\begin{description}
 \short The interface \src{CommonElement} is the parent interface of \src{CommonDockable} and \src{CommonStation}.
 \why Represents the \src{DockElement}.
 \clients The type system should now enfoce the correct implementation of all the different methods. Clients may need to update custom \src{DockStation}s.
\end{description}

\subsubsection{AdjacentDockFactories and PerspectiveElements}
\begin{description}
 \short \src{AdjacentDockFactory}s can now also write meta data for \linebreak \src{PerspectiveElement}s.
 \why More support for the perspective API.
 \clients Clients implement \src{AdjacendDockFactory} may need to update the implementation.
\end{description}

\subsubsection{PopupController accessible}
\begin{description}
 \short The \src{PopupController} is now accessible for clients by calling \linebreak \src{getPopupController}, a method of \src{DockController}.
 \why Allows customization of the popups.
 \clients Clients can now install their custom \src{DockPopupMenuFactory} and change the way popup menus behave.
\end{description}

\subsubsection{DockRelocator updated}
\begin{description}
 \short \src{DockRelocator} is now an interface.
 \why Part of an ongoing effort to hide all controller classes behind interfaces.
 \clients Clients may need to extend from one of the subclasses of \src{DockRelocator} instead of \src{DockRelocator} directly.
\end{description}

\end{document}
